Typical HAL NOR use cases for migration

This section provides information about typical HAL NOR use cases for migration.

Important

HAL NOR supports 16-bit memory only. 8-bit memory support will be added later.

Important

In HAL2, additional APIs and CFI commands are available. For details, refer to the HAL2 documentation.

Important

Most APIs are split according to the command set of the device.

  • In HAL1, the command sets are read and saved by the driver internally.

  • In HAL2, the HAL_NOR_CFI_000x APIs must be used to execute the requested command:

    • HAL_NOR_CFI_0001 for Command Set ID 0001 (Intel/Sharp Extended)

    • HAL_NOR_CFI_0002 for Command Set ID 0002 (AMD/Fujitsu Standard)

    • HAL_NOR_CFI_0003 for Command Set ID 0003 (Intel Standard)

Use case: program and read operations

HAL1

HAL2

The HAL NOR driver is designed to use a high-level API that abstracts the CFI commands.

The HAL NOR driver provides the user with CFI 0001, 0002, and 0003 APIs for program and read operations.

Sequence diagram

Program and read operations

@startuml == Prerequisite: initialization and configuration == == Process == "User Application"->"HAL NOR Driver" : HAL_NOR_Program() note right: Program data alt Success or Recoverable error "HAL NOR Driver"-->"User Application": HAL_OK or HAL_BUSY note right: Return status else Unrecoverable error "HAL NOR Driver"-->"User Application": HAL_ERROR note right: Unrecoverable error "User Application"->"HAL NOR Driver" : HAL_NOR_ReturnToReadMode() note right: Reinitialize NOR end alt "User Application"->"HAL NOR Driver" : HAL_NOR_ReadBuffer() note right: Read data "HAL NOR Driver"-->"User Application": HAL_OK or HAL_BUSY or HAL_ERROR note right: Return status @enduml

Note

In HAL1, the program API passes the data to be written by address. In HAL2, the APIs pass the data by value because one data item is used at a time.

Code snippet

HAL1

HAL2 

/* Program API */
HAL_NOR_Program(&hnor,
                (uint32_t *)NOR_StartAddress,
                &program_data
                /* --- */
               );
HAL_NOR_ReturnToReadMode(&hnor);
/* Read API */
HAL_NOR_ReadBuffer(&hnor,
                   (uint32_t *)NOR_StartAddress,
                   read_data_buffer,
                   buffer_size
                  );

/* Program API for command set ID 0001 */
HAL_NOR_CFI_0001_Program(&hnor,
                         (uint32_t *)NOR_StartAddress,
                         program_data,
                         1000 // 1000 ms
                        );
HAL_NOR_CFI_0001_Reset(&hnor);
/* Read API for command set ID 0001 */
HAL_NOR_CFI_0001_ReadArray(&hnor,
                           (uint32_t *)NOR_StartAddress,
                           read_data_buffer,
                           buffer_size
                          );

Key changes

  1. HAL2 splits most APIs by command set ID (CFI 0001/0002/0003).

  2. HAL2 uses command-set specific reset and read-array APIs (HAL_NOR_CFI_000x_Reset() and HAL_NOR_CFI_000x_ReadArray()).

Use case: read operations of CFI information

HAL1

HAL2

The user reads the CFI information using HAL_NOR_Read_CFI(), then returns to read mode using HAL_NOR_ReturnToReadMode().

The user reads the CFI information using HAL_NOR_CFI_ReadDeviceInfo(), then resets the device to return to read mode using HAL_NOR_CFI_000x_Reset().

Sequence diagram

Read operations of CFI information

@startuml == Prerequisite: Initialization and configuration == == Process == "User Application" -> "HAL NOR Driver" : HAL_NOR_Read_CFI() note right: Read CFI data "HAL NOR Driver" -> "User Application" : HAL_OK or HAL_ERROR note right: Return status "User Application"->"HAL NOR Driver" : HAL_NOR_ReturnToReadMode() note right: Return the device to read mode "User Application"->"HAL NOR Driver" : HAL_NOR_ReadBuffer() note right: Read data from NOR memory. "HAL NOR Driver"->"User Application" : HAL_OK or HAL_ERROR note right: Return status @enduml

Code snippet

HAL1

HAL2 

NOR_HandleTypeDef hnor;
NOR_CFITypeDef nor_cfi;
/* Read CFI info */
HAL_NOR_Read_CFI(&hnor, &nor_cfi);
/* Return to read mode */
HAL_NOR_ReturnToReadMode(&hnor);
/* Read data from the NOR flash memory */
HAL_NOR_ReadBuffer(&hnor,
                   (uint32_t *)NOR_StartAddress,
                   read_data_buffer,
                   buffer_size
                  );

hal_nor_handle_t hnor;
hal_nor_cfi_device_info_t device_info;
/* Retrieve NOR flash CFI information */
HAL_NOR_CFI_ReadDeviceInfo(&hnor, &device_info);
/* Reset the NOR flash device */
HAL_NOR_CFI_0001_Reset(&hnor);
/* Read data from the NOR flash memory */
HAL_NOR_CFI_0001_ReadArray(&hnor
                           (uint32_t *)NOR_StartAddress,
                           read_data_buffer,
                           buffer_size
                          );

Key changes

  1. HAL2 uses HAL_NOR_CFI_ReadDeviceInfo() and then a command-set specific reset API (HAL_NOR_CFI_000x_Reset()).

  2. HAL2 uses command-set specific read APIs (HAL_NOR_CFI_000x_ReadArray() or HAL_NOR_CFI_000x_Read()).